%****************************************************************************%
%* DIET Programmer's Guide - chapter one                                    *%
%*                                                                          *%
%*  Author(s):                                                              *%
%*    - Philippe COMBES (Philippe.Combes@ens-lyon.fr)                       *%
%*                                                                          *%
%* $LICENSE$                                                                *%
%****************************************************************************%
%* $Id: start.tex,v 1.9 2008/07/14 09:33:34 vpichon Exp $
%* $Log: start.tex,v $
%* Revision 1.9  2008/07/14 09:33:34  vpichon
%*
%* documentation section move UserManual => ProgrammersGuide
%*
%* Revision 1.8  2006/11/16 14:09:20  eboix
%* - Programmers guide converted from autotools to cmake.
%* - cmake summary deported to Cmake sub-dir.   --- Injay2461
%*
%* Revision 1.7  2006/01/25 17:26:04  pfrauenk
%* CoRI : Some useful information about CoRI now available
%*
%* Revision 1.6  2005/08/22 08:06:03  ycaniou
%* Re-form the source start.tex with no changes.
%* Correct the Makefile.am so that know it does not only compile by typing
%*   make in the Programmer's guide but also with the more common make doc
%*
%* Revision 1.5  2005/04/13 08:50:39  hdail
%* Cleaning up references to libUtilsCichlid.la.
%*
%* Revision 1.4  2004/06/15 14:08:07  bdelfabr
%* adding files in table for data persistency
%*
%* Revision 1.3  2004/01/07 21:55:37  cpera
%* Add brief text on autotools and references.
%*
%* Revision 1.2  2003/11/28 11:54:44  pcombes
%* Add-ons about maintainer mode.
%*
%* Revision 1.1  2003/09/17 14:41:28  pcombes
%* Split the .tex according to its chapters.
%****************************************************************************%


\section{Using CVS}

There are two ways to get the source code for developers. DIET is
published under two forms of archive, and one of them contains all
files that are necessary to program in DIET: it is the maintainer mode
archive. But the most current way of getting the source files is to
use the CVS.

Here are the CVS environment variables to set (of course, the
programmer needs an account on the GRAAL server so far):
\begin{description}
\item{\sf CVSROOT} \textsf{ = :ext:graal.ens-lyon.fr:/home/CVS}
\item{\sf CVSUMASK} \textsf{ = 000}
\item{\sf CVS\_RSH} \textsf{ = ssh}
\item{\sf CVSEDITOR [optional]} your favorite editor.
\end{description}

Once all these variables are set, just execute\\
\centerline{\sf cvs checkout GRAAL/devel/diet}\\


As many developers work on DIET simultaneously, it is important to
commit files only when it is proved that it will not hinder the other
developers in their own work. The consensual use of simultaneous
developments is to perform an update of each file just before editing
it, then merge with the changes committed in-between and test the
local version to make sure that basic functionnalities are not
buggy. Commit the local version at last.

Deep changes should be preceeded by a discussion on the mailing list
\url{diet-dev@ens-lyon.fr} with all DIET developers.

On each commit, a log message is required. It is important that this
log message is clear enough for other developers to understand the
outlines of the changes, but it should remain concise. Try not to
exceed two 80 character-lines.  Indeed, the log messages are dumped
into the files headers.


\section{Bootstrapping}

The compilation of DIET is managed by Makefiles generated and
configured with \cmake.
\cmake generates a Makefile in each directory where there is a
\CMakeLists\ file.

If you have to add a file, or if you have to modify the compilation
dependence of an existing file in DIET, then you will have to modify a
\CMakeLists. 

\section{Configuring and compiling as a programmer}

Among the numerous options provided by the top \CMakeLists\ a
programmer should set the \verb+CMAKE_BUILD_TYPE+ to \verb+Maintainer+.
When doing so the compilers and linkers go paranoid and try to report
about most of the warning they are aware of.
Since the warning flags are compiler dependent this Maintainer build mode
is alas only available for GCC.

Here is the example of my source tree, got from the CVS server:
\begin{verbatim}
~ > cvs checkout GRAAL/devel/diet
~ > cd GRAAL/devel/diet
~ > mkdir Build ; cd Build
~ > cmake -DCMAKE_BUILD_TYPE:STRING=Maintainer <options> ..
...
\end{verbatim}

Finally, it is also strongly recommended to test your modifications
with a whole platform before submitting them.
A script \texttt{local\_platform} is given with the distribution
(in \textsf{bin/scripts}), which launches
\begin{itemize}
\item a mini LDAP base with the services \textsf{base/mult},
  \textsf{base/plus}, and \textsf{dgemm}, with the output of the FAST
  bencher that Martin made on his machine (but who cares right values
  for tests ?) ;
\item and four NWS entities: the three mandatory ones,
  \texttt{nws\_nameserver}, \texttt{nws\_memory} and
  \texttt{nws\_forecaster}, and one sensor for the local machine,
  \texttt{nws\_sensor} ; their ports are the ones used in the default
  configuration files of DIET.
\end{itemize}
So, as it is quite easy to launch a local platform, please do not
hesitate configuring DIET with FAST.

\section{Documentation}
\label{section:compiling-documentation}

Documentation is in \verb+CVS_DIET_HOME/doc+. It includes the LaTeX-based 
user's guide, the developer's guide and the doxygenated documentation.
Compilation of the documentation is very sensitive to the version of your
\LaTeX\ compiler and it also relies on many sub-dependencies
  (e.g. \verb+doxygen+ or \verb+fig2dev+)

\begin{itemize}
\item
  \verb+cd CVS_DIET_HOME/doc+
\item
  \verb+mkdir build+
\item
  \verb+cd build+
\item
  \verb+ccmake ..+ to enter the GUI
  \begin{itemize}
  \item press \verb+c+ (equivalent of bootstrap.sh of the autotools)
  \item toggle the desired options 
  \item specify the \verb+CMAKE_INSTALL_PREFIX+ parameter (if you wish
     to install in a directory different from \verb+/usr/local+,
  \item press \verb+c+ again, for checking required dependencies
  \item check all the parameters preceded with the * (star) character
     whose value was automatically retrieved by \verb+cmake+.
  \item provide the required information i.e. fill in the proper values
     for all parameters whose value is terminated by NOT-FOUND
  \item iterate the above process of parameter checking, toggle/specification
     and configuration until all configuration information is satisfied
  \item press \verb+g+ to generate the makefile
  \item press \verb+q+ to exit ccmake
  \end{itemize}
\item
  \verb+make+ in order to classically launch the compilation process
\item
  \verb+make install+ when installation is required
\end{itemize}


\section{Before altering DIET ...}

Once your environment has been set up, you are almost ready to add
your modifications in DIET. But, unless you are very well informed
about the way DIET is structured, please respect the following steps:
\begin{enumerate}
\item Decide which DIET entities are concerned by your changes.
\item ( For Eddy, are my changes \underline{\textbf{really}} useful ? )
\item Read carefully the paragraphs in chapter \ref{ch:tree} about the
  directory that deal with this entity (even if reading the chapter in
  a whole can only be a good thing ...).
\item Read \underline{\textbf{carefully}} the Coding Standards in
  chapter \ref{ch:CS}.
\item Include your modifications in the compilation chain (you may
  have nothing to do if you do not create any file, except your
  changes modify the dependencies)
\end{enumerate}


\section{Adding a file or a directory in the compilation chain}

%\fixme{Christophe - please check up and complete this part}\\

Understanding the conception of a \CMakeLists\ in DIET is quite
straightfoward.
Basically, we have to build two libraries (\textsf{DIET\_client}
and \textsf{DIET\_SeD}) and one binary executable (\textsf{dietAgent})
using great amount of common source code.

\subsection{Adding a file in a ``terminal'' directory}

A ``terminal'' directory is a directory where a library or an
executable is generated.\\

Let us take the example of the generation of the executable
\textsf{dietAgent}.
It is defined in the \texttt{src/agent/CMakeLists.txt}
with the following \cmake instructions:
\begin{verbatim}
ADD_EXECUTABLE( dietAgent dietAgent.cc )
TARGET_LINK_LIBRARIES( dietAgent AgentCommon)
\end{verbatim}

For the \textsf{DIET\_SeD} library, for instance, it would be:
\begin{verbatim}
SET( DIET_SeD_SOURCES
  DIET_server.cc
  DataMgrImpl.cc
  SeDImpl.cc
)
ADD_LIBRARY( DIET_SeD ${DIET_SeD_SOURCES} )
TARGET_LINK_LIBRARIES( DIET_SeD
  CorbaCommon
  IDLAgent IDLCommon
  UtilsCommon UtilsNodes UtilsSeDClt UtilsVector
  ${OMNIORB4_LIBRARIES}
)
\end{verbatim}

Thus, adding a \texttt{.cc} file in a ``terminal'' directory implies
only adding its name in the \texttt{*\_SOURCES} variable.

\subsection{Adding a file in a ``non-terminal'' directory}

In a ``non-terminal'' directory, we have to generate temporary
libraries that will be included in the final libraries
or executables. Of course it is possible to group all files of the
directory in a big library, but this would make the final libraries
and executables much bigger than necessary, since they would include
dead code (code that they would never use).
This is why we decided to group the files of each directory into
different libraries, depending on the ``destinations''
of the modules
\footnote{A module consists of a \textsf{.h} or
\textsf{.hh} and its associated \textsf{.c} or \textsf{.cc}.
For instance, the header and the implementation of a class.},
i.e.~depending on the final binaries that use them.
Please refer to the dependency table \ref{t:dep}, which every
DIET programmer is asked to maintain whereas he alters the repartition
of these libraries, because of new files or modifications that
change the dependencies.  \\

\noindent
To add a new module in a non-terminal directory,
\begin{enumerate}
\item Add its line in the table \ref{t:dep} (in the section of its
  directory), and put an 'x' in each column where it is used.
\item Then you can find to which temporary library you must add it:
  the library that matches the same combination of 'x' in the table,
  or if none, a new one.
\item Add the \textsf{.cc} file in the corresponding
  \texttt{*\_SOURCES} variable of the \CMakeLists\ in the directory.
\end{enumerate}

\begin{table}[h]
 \footnotesize
 \centering
 \fixme{Bruno - Pease add your files for data persistency ...}
 \begin{tabular}[c]{|l|c|c|c|l|}
  \hline
  Modules  &
  \begin{minipage}[c]{1.65cm}
   \centering used in\\ \texttt{dietAgent}
  \end{minipage}                  &
  \begin{minipage}[c]{1.65cm}
   \centering used in\\ \texttt{DIET\_SeD}
  \end{minipage}                  &
  \begin{minipage}[c]{1.65cm}
   \centering used in\\% \hspace*{-5pt}
   \texttt{DIET\_client}
  \end{minipage}                  &
  \textsf{.la} library to add to\\[5pt]
  \hline

  % AGENT
  \multicolumn{1}{|l}{\textsf{src/agent}:} &
  \multicolumn{4}{l|}{\texttt{dietAgent}}\\[5pt]

  \textit{all files}              & x &   &   & \emph{none}\\[5pt]
  \hline

  % CLIENT
  \multicolumn{1}{|l}{\textsf{src/client}:} &
  \multicolumn{4}{l|}{\texttt{libDIET\_client.[a|so]}}\\[5pt]

  \textit{all files}              &   &   & x & \emph{none}\\[5pt]
  \hline

  % CORBA
  \multicolumn{1}{|l}{\textsf{src/CORBA}:} &
  \multicolumn{4}{l|}{\texttt{libCorbaCommon.la}}\\[5pt]

  \texttt{marshalling}            & x & x & x & \texttt{libCorbaCommon.la}\\
  \texttt{ORBMgr}                 & x & x & x & \texttt{libCorbaCommon.la}\\[5pt]
  \hline

  % CORBA/idl
  \multicolumn{1}{|l}{\textsf{src/CORBA/IDL}:} &
  \multicolumn{4}{l|}{\texttt{libIDLCommon.la libIDLAgent.la
                              libIDLLA.la libIDLMA.la}}\\[5pt]

  \texttt{Agent[Dyn]SK}           & x & x &   & \texttt{libIDLAgent.la}\\
  \texttt{LocalAgent[Dyn]SK}      & x &   &   & \texttt{libIDLLA.la}\\
  \texttt{MasterAgent[Dyn]SK}     & x &   & x & \texttt{libIDLMA.la}\\
  \texttt{Callback[Dyn]SK}        & x & x & x & \texttt{libIDLCommon.la}\\
  \texttt{SeD[Dyn]SK}             & x & x & x & \texttt{libIDLCommon.la}\\
  \texttt{common\_types[Dyn]SK}   & x & x & x & \texttt{libIDLCommon.la}\\
  \texttt{response[Dyn]SK}        & x & x & x & \texttt{libIDLCommon.la}\\
  \texttt{DataMgr[Dyn]SK}        & x & x & x & \texttt{libIDLAgent.la}\\
  \texttt{LocMgr[Dyn]SK}        & x & x & x & \texttt{libIDLAgent.la}\\[5pt]
  \hline

  % SED

  \multicolumn{1}{|l}{\textsf{src/SeD}:} &
  \multicolumn{4}{l|}{\texttt{libDIET\_SeD.[a|so]}}\\[5pt]

  \textit{all files}              &   & x &   & \emph{none}\\[5pt]
  \hline

  % UTILS

  \multicolumn{1}{|l}{\textsf{src/utils}:} &
  \multicolumn{4}{l|}{\texttt{libUtilsCommon.la
                             libUtilsSeDClt.la  libUtilsNodes.la}}\\[5pt]

  \texttt{Counter}                & x & x &   & \texttt{libUtilsNodes.la}\\
  \texttt{Cori*}                  & x & x &   & \texttt{libUtilsNodes.la}\\
  \texttt{CORIMgr}                & x & x &   & \texttt{libUtilsNodes.la}\\
  \texttt{debug}                  & x & x & x & \texttt{libUtilsCommon.la}\\
  \texttt{DIET\_data}             & x & x & x & \texttt{libUtilsCommon.la}\\
  \texttt{DIET\_mutex}            &   & x & x & \texttt{libUtilsSeDClt.la}\\
  \texttt{FASTMgr}                & x & x &   & \texttt{libUtilsNodes.la}\\
  \texttt{ms\_function}           & x & x & x & \texttt{libUtilsCommon.la}\\
  \texttt{Parsers}                & x & x & x & \texttt{libUtilsCommon.la}\\
  \texttt{ServiceTable}           & x & x &   & \texttt{libUtilsNodes.la}\\
  \texttt{statistics}             & x & x & x & \texttt{libUtilsCommon.la}\\[5pt]
  \hline


 \end{tabular}
 \caption{Dependencies of the final binaries from the temporary
 libraries}
 \label{t:dep}
\end{table}


\noindent
\fbox{\textbf{NB}} The particular case of the sub-directory
\textsf{IDL} will be discussed in section \ref{s:IDL}. Indeed, it
cannot be processed as the other ones, since the \textsf{.idl} files
are the true source files. The \textsf{.cc} and \textsf{.hh} files are
``built sources'' generated from the \textsf{.idl}.



\subsection{Adding a directory}

We will discuss here the criteria that makes the creation of a new
directory sensible. We will just mention, as exposed in the
\textit{Coding Standards} (chapter \ref{ch:CS}), that such changes
should be discussed on the developers mailing list,
\url{diet-dev@ens-lyon.fr}.  \\ We will not discuss neither the way to
add the directory in the CVS repository, since this has nothing to do
here.

Once it has been decided to add a new directory, and once its own
\CMakeLists\ is written, then it has to be reported
in the \CMakeLists\ of its parent directory.
It should be added with a \texttt{ADD\_SUBDIRECTORY} command.
